<!DOCTYPE html>
<html>
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta http-equiv="Content-language" content="en">
	<meta name="description" content="Scalable Reactive Model Transformations">
	<meta name="MobileOptimized" content="width" />
	<meta name="HandheldFriendly" content="true" />
	<meta name="viewport" content="width=device-width, initial-scale=1.0" />

	<script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
	<script type="text/javascript" src="/viatra/js/googleAnalytics.js"></script>
	<script type="text/javascript" src="/viatra/js/magnific-popup.video.js"></script>
	<script type="text/javascript" src="/viatra/js/magnific-popup.min.js"></script>
	<script type="text/javascript" src="/viatra/js/functions.js"></script>
	<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.6.9/angular.min.js"></script>
	<script src="/viatra/angular/viatra.js"></script>
	<script src="/viatra/highlight.js/highlight.min.js"></script>

    <link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
    <script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>  

	<link rel="shortcut icon" type="image/x-icon" href="/viatra/favicon.ico" />
	<title>Viatra - Scalable reactive model transformations</title>
	<link type="text/css" rel="stylesheet" href="/viatra/css/bootstrap.min.css" />
	<link type="text/css" rel="stylesheet" href="/viatra/css/style.css" />
	<link type="text/css" rel="stylesheet" href="/viatra/css/media.css" />
	<link href='https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'> 
	<link href='https://fonts.googleapis.com/css?family=Open+Sans+Condensed:300italic,700,300' rel='stylesheet' type='text/css'>
	<link rel="stylesheet" href="https://use.fontawesome.com/ef6567f233.css">

	<link rel="stylesheet" href="/viatra/highlight.js/styles/foundation.min.css">
	<link rel="stylesheet" type="text/css" href="/viatra/css/asciidoctor.css"/>

</head>

<body ng-app="viatra" ng-controller="main" class="cloak">
<ng-include src="'/viatra/angular/blocks/header.html'"></ng-include>

<div class="clear"></div>
<div id="body_wrapper">
<h1 class="page_title">Graphical Editing of Queries</h1>


<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This section introduces the graphical query editor included in VIATRA 2.1 (released with Eclipse 2018-12). The goal of this editor is to support creating model queries in a graphical syntax, while maintaining compatibility with the existing infrastructure of VIATRA, including both the runtime and query development environment.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_requirements_and_installation">Requirements and Installation</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The current version of the editor is based on Sirius 6.0 (and thus transitively requires Eclipse Oxygen as well). Furthermore, it requires a current version of VIATRA 2.1 IDE installed as well. To download that version, use the following p2 repository: <code><a href="http://download.eclipse.org/viatra/updates/release/latest" class="bare">http://download.eclipse.org/viatra/updates/release/latest</a></code></p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/tools/vgql_install.png" alt="vgql install" height="300"></span></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_graphical_query_projects">Graphical Query Projects</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Graphical query projects are specialized VIATRA query projects where graphical query definitions are stored in one source folder, and another source folders contain the textual equivalents of the graphical queries and the generated Java source code to integrate the queries into existing applications.</p>
</div>
<div class="paragraph">
<p>The following figure describes the default graphical query project structure:  a source folder <code>src</code> (presented in red) contains <code>vgql</code> files describing graphical queries, and in a source folder <code>vgql-gen</code> (depicted in blue) contains <code>vql</code> files generated from the graphical query definitions. Each generated <code>vql</code> file represent a <code>vgql</code> file with the same filename, and both are stored in corresponding Java packages. Finally, a <code>src-gen</code> folder (depicted in green) is used to store the generated Java code from the vql files.</p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/tools/vgql_project.png" alt="vgql project" height="300"></span></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_getting_started_with_graphical_query_editing">Getting Started with Graphical Query Editing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>A Graphical Query Project can be initialized with an appropriate project wizard. All source folders and builders are correctly set up, meaning the environment is ready to draw graph patterns and then get the appropriate generated code from it.</p>
</div>
<div class="sect2">
<h3 id="_initializing_a_new_diagram">Initializing a New Diagram</h3>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create Graphical Query Project
<span class="image"><img src="images/tools/new_vgql_project.png" alt="new vgql project" height="300"></span></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Graphical query models can be created with the <code>Graphical Query Definition</code> wizard, selecting a source folder (within a Graphical Query Project), a package and a file name.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Create Graphical Query Definition
<span class="image"><img src="images/tools/new_vgql_file.png" alt="new vgql file" height="300"></span></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>After the wizard finishes, a new diagram is opened for the created file, where the pattern definitions can be edited using the usual tools.</p>
</div>
</div>
<div class="sect2">
<h3 id="_creating_the_first_pattern">Creating the First Pattern</h3>
<div class="paragraph">
<p>Before editing, the required ecore metamodels are to be added to the diagram in the Properties view.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Add an Ecore Metamodel
<span class="image"><img src="images/tools/vgql_add_metamodel.png" alt="vgql add metamodel" height="300"></span></p>
</li>
</ol>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The editor tries to add the required plug-in dependencies automatically to the project. In rare case this may fail, causing the generated vql files will be erroneous. In such cases the generated vql files have a quick fix to add this dependency to the project.
</td>
</tr>
</table>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Metamodel dependency
<span class="image"><img src="images/tools/dependency_quick_fix.png" alt="dependency quick fix" height="300"></span></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Our first pattern will be used to enumerate all members of the EClass <code>HostInstance</code>. For this, we need a pattern with a single, typed parameter.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>First pattern
<span class="image"><img src="images/tools/vgql_first_pattern.png" alt="vgql first pattern" height="300"></span></p>
</li>
</ol>
</div>
<div class="paragraph">
<p>In order to ensure the created patterns are well-formed VIATRA queries, the queries can be validated using the default Sirius-based validators: select <code>Validate Diagram</code> from the pop-up menu of the diagram.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
In case of errors in the specification, the generated VQL files will be erroneous. In such cases it is recommended to re-validate the diagram and look at the provided error reports to fix the issues.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_evaluating_query_results">Evaluating Query Results</h3>
<div class="paragraph">
<p>When everything works, an error-free <code>vql</code> file is generated from the graphical patterns automatically. At this point, the patterns can be loaded to the <code>Query Results</code> view using the standard components.</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Using the Query Results View
<span class="image"><img src="images/tools/vgql_query_results.png" alt="vgql query results" height="300"></span></p>
</li>
</ol>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
This integration assumes that the <code>vql</code> file is generated, so it requires the query definitions to be saved, and a short delay may be necessary after save for the view to see the latest changes. When in doubt, wait until the Eclipse build job has finished.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_missing_feature_and_known_issues">Missing Feature and Known Issues</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The graphical pattern editor in VIATRA 2.1.0 is considered experimental, and there are a few known issues that are planned to be addressed in a later release. These issues are maintained in <a href="https://bugs.eclipse.org/bugs/buglist.cgi?list_id=17930299&amp;product=Viatra&amp;query_format=advanced&amp;status_whiteboard=vgql-editor&amp;status_whiteboard_type=allwordssubstr">Bugzilla</a>.</p>
</div>
</div>
</div>

	<script>hljs.initHighlighting()</script>
</div>	

<div class="clear"></div>
<ng-include src="'/viatra/angular/blocks/footer.html'"></ng-include>

</body>
</html>